home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / tcl / tcl67.lha / tcl6.7 / doc / Fork.3 < prev    next >
Text File  |  1993-01-31  |  6KB  |  151 lines
  1. '\"
  2. '\" Copyright 1989 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/tcl/man/RCS/Fork.3,v 1.5 93/01/31 15:35:34 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .so man.macros
  13. .HS Tcl_Fork tcl
  14. .BS
  15. .VS
  16. .SH NAME
  17. Tcl_Fork, Tcl_WaitPids, Tcl_DetachPids \- manage child processes
  18. .SH SYNOPSIS
  19. .nf
  20. \fB#include <tcl.h>\fR
  21. .sp
  22. int
  23. \fBTcl_Fork\fR( )
  24. .sp
  25. int
  26. \fBTcl_WaitPids\fR(\fInumPids, pidPtr, statusPtr\fR)
  27. .sp
  28. int
  29. \fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
  30. .SH ARGUMENTS
  31. .AS int *statusPtr
  32. .AP int numPids in
  33. Number of process ids contained in the array pointed to by \fIpidPtr\fR.
  34. .AP int *pidPtr in
  35. Address of array containing \fInumPids\fR process ids.
  36. .AP int *statusPtr out
  37. Address of place to store status returned by exited/suspended process.
  38. .BE
  39.  
  40. .SH DESCRIPTION
  41. .PP
  42. These procedures keep track of child processes in order to make it
  43. easier for one application to manage several children.
  44. If an application uses
  45. the UNIX \fIfork\fR and \fIwait\fR kernel calls directly,
  46. problems occur in situations like the following:
  47. .IP [1]
  48. One part of an application creates child C1.  It plans to
  49. let the child run in background, then later wait for it to
  50. complete.
  51. .IP [2]
  52. Some other part of the application creates another child C2,
  53. not knowing anything about C1.
  54. .IP [3]
  55. The second part of the application uses \fIwait\fR to wait for C2
  56. to complete.
  57. .IP [4]
  58. C1 completes before C2, so C1 is returned by the
  59. \fIwait\fR kernel call.
  60. .IP [5]
  61. The second part of the application doesn't recognize C1, so it
  62. ignores it and calls \fIwait\fR again.  This time C2
  63. completes.
  64. .IP [6]
  65. The first part of the application eventually decides to wait
  66. for its child to complete.  When it calls \fIwait\fR there are
  67. no children left, so \fIwait\fR returns an error and the
  68. application never gets to examine the exit status for C1.
  69. .PP
  70. The procedures \fBTcl_Fork\fR, \fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR
  71. get around this problem by keeping a table of child processes and
  72. their exit statuses.
  73. They also provide a more flexible waiting
  74. mechanism than the \fIwait\fR kernel call.
  75. Tcl-based applications should never call \fIfork\fR and
  76. \fIwait\fR directly;  they should use \fBTcl_Fork\fR,
  77. \fBTcl_WaitPids\fR, and \fBTcl_DetachPids\fR.
  78. .PP
  79. \fBTcl_Fork\fR calls \fIfork\fR and returns the result of
  80. the \fIfork\fR kernel call.
  81. If the \fIfork\fR call was successful then \fBTcl_Fork\fR also
  82. enters the new process into its internal table of child
  83. proceses.
  84. If \fIfork\fR returns an error then \fBTcl_Fork\fR returns that
  85. same error.
  86. .PP
  87. \fBTcl_WaitPids\fR calls \fIwait\fR repeatedly until one of the processes
  88. in the \fIpidPtr\fR array has exited or been killed or suspended by a
  89. signal.
  90. When this occurs, \fBTcl_WaitPids\fR returns the process
  91. identifier for the process and stores its wait status at
  92. \fI*statusPtr\fR.
  93. If the process no longer exists (it exited or was killed by a signal),
  94. then \fBTcl_WaitPids\fR removes its entry from the internal
  95. process table.
  96. If \fIwait\fR returns a process that isn't
  97. in the \fIpidPtr\fR array, \fBTcl_WaitPids\fR saves its wait
  98. status in the internal process table and calls \fIwait\fR again.
  99. If one of the processes in the \fIpidPtr\fR array has already
  100. exited (or suspended or been killed) when \fBTcl_WaitPids\fR
  101. is called, that process and its wait status are returned
  102. immediately without calling \fIwait\fR.
  103. .PP
  104. \fBTcl_WaitPids\fR provides two advantages.  First, it allows
  105. processes to exit in any order, and saves their wait statuses.
  106. Second, it allows waiting on a number of processes simultaneously,
  107. returning when any of the processes is returned by \fIwait\fR.
  108. .PP
  109. \fBTcl_DetachPids\fR is used to indicate that the application
  110. no longer cares about the processes given by the \fIpidPtr\fR
  111. array and will never use \fBTcl_WaitPids\fR to wait for them.
  112. This occurs, for example, if one or more children are to be
  113. executed in background and the parent doesn't care whether
  114. they complete successfully.
  115. When \fBTcl_DetachPids\fR is called, the internal process
  116. table entries for the processes are marked so that the
  117. entries will be removed as soon as the processes exit or
  118. are killed.
  119. .PP
  120. If none of the pids passed to \fBTcl_WaitPids\fR exists in
  121. the internal process table, then -1 is returned and \fIerrno\fR
  122. is set to ECHILD.
  123. If a \fIwait\fR kernel call returns an error,
  124. then \fBTcl_WaitPids\fR returns that same error.
  125. If a \fIwait\fR kernel call returns a process that isn't in
  126. the internal process table,  \fBTcl_WaitPids\fR panics and
  127. aborts the application.
  128. If this situation occurs, it means that a process has been
  129. created without calling \fBTcl_Fork\fR and that its exit
  130. status is about to be lost.
  131. .PP
  132. \fBTcl_WaitPids\fR defines wait statuses to have type \fIint\fR,
  133. which is correct for POSIX and many variants of UNIX. 
  134. Some BSD-based UNIX systems still use type \fIunion wait\fR for
  135. wait statuses;  it should be safe to cast a pointer to a
  136. \fIunion wait\fR structure to \fI(int *)\fR before passing
  137. it to \fBTcl_WaitPids\fR as in the following code:
  138. .nf
  139. .RS
  140.  
  141. \fBunion wait status;
  142. int pid1, pid2;
  143. \&...
  144. pid2 = Tcl_WaitPids(1, &pid1, (int *) &status);\fR
  145. .RE
  146. .fi
  147.  
  148. .SH KEYWORDS
  149. background, child, detach, fork, process, status, wait
  150. .VE
  151.